Add Web Components patterns to web integration skill by mattpodwysocki · Pull Request #13 · mapbox/mapbox-agent-skills

mattpodwysocki · 2026-02-04T18:46:39Z

Summary

Adds comprehensive Web Components (Custom Elements) patterns as a framework-agnostic alternative to framework-specific integration patterns.

What's Added

New Section in SKILL.md:

Basic Custom Element - Standard pattern with connectedCallback / disconnectedCallback
Attribute Configuration - Reading map config from HTML attributes
Shadow DOM Pattern - Encapsulated styles (optional, more complex)
Reactive Attributes - Using observedAttributes + attributeChangedCallback for live updates
Framework Usage Examples - How to use the same component in React, Vue, Svelte, vanilla JS

Patterns Covered

Basic Web Component

class MapboxMap extends HTMLElement {
  connectedCallback() {
    // Initialize map
    this.map = new mapboxgl.Map({ container: this, ... });
  }
  
  disconnectedCallback() {
    // CRITICAL: cleanup
    this.map?.remove();
  }
}
customElements.define('mapbox-map', MapboxMap);

Usage Across Frameworks

The same component works without modification in:

React - Via ref and custom event listeners
Vue - Via template refs and @event bindings
Svelte - Via bind:this and on:event
Vanilla JS - Direct HTML usage

Advanced Patterns

Shadow DOM for style encapsulation
Reactive attributes that update map on attribute change
Custom events for map interactions
Exposed methods via getMap()

Benefits

✅ Framework-agnostic - write once, use everywhere
✅ No framework lock-in - web platform standard
✅ Maximum portability - ideal for component libraries
✅ Future-proof - based on web standards
✅ Encapsulation - clear API via attributes

When to Use

Building component libraries used across multiple frameworks
Micro-frontends architecture
Maximum reusability requirements
Want to avoid framework-specific code
Need a portable, standard-based solution

When to Use Framework Components Instead

Deep framework integration needed (state management, routing)
Team already committed to specific framework
Using framework-specific features (hooks, Composition API)
Team more familiar with framework patterns

Testing

Added comprehensive Web Components section
Included basic, Shadow DOM, and reactive patterns
Usage examples for React, Vue, Svelte, vanilla JS
Updated skill description to mention Web Components
Updated main README.md
Follows existing skill standards

Addresses user request to add Web Components as framework-agnostic alternative to framework-specific patterns.

Comprehensive Web Components (Custom Elements) patterns showing: - Basic Custom Element with lifecycle callbacks - Attribute-based configuration - Shadow DOM encapsulation (optional pattern) - Reactive attributes with observedAttributes - Usage examples in React, Vue, Svelte, and vanilla JS - Framework-agnostic approach for maximum portability Benefits of Web Components pattern: - Works across all frameworks without modification - No framework lock-in - Standard web platform API - Ideal for component libraries and micro-frontends Updated skill description and README to highlight Web Components as framework-agnostic alternative to framework-specific patterns. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Add terms for navigation, store locator, data visualization, and web components: - dropin: Android Navigation SDK NavigationView - millis: currentTimeMillis suffix - Haversine: distance calculation formula - Jenks: statistical classification method - colorbrewer: ColorBrewer color scales tool - htmlelement: Web Components HTMLElement - customelements: Web Components API - currenttime: time-related functions

AndrewSepic · 2026-02-10T21:28:04Z

skills/mapbox-web-integration-patterns/SKILL.md

+    <mapbox-map
+      ref={mapRef}
+      access-token={import.meta.env.VITE_MAPBOX_ACCESS_TOKEN}
+      style="mapbox://styles/mapbox/standard"


The style property is reserved in React for the css style prop. This should be renamed to mapStyle or something similar to not throw in React.

Move Web Components to new 'Advanced Patterns' section with clear guidance: **When to use:** - Design systems & component libraries across frameworks - Micro-frontends with multiple frameworks - Multi-framework organizations - Framework migration scenarios - W3C standard for long-term stability **When NOT to use:** - Single-framework applications (use framework-specific patterns) - Need deep framework integration (hooks, composition API) - Team proficient with framework patterns - Prefer simplicity over portability Changes: - Updated skill description to focus on framework-specific patterns - Moved Web Components after all framework patterns - Added prominent warning at section start - Condensed examples (removed Shadow DOM pattern) - Clear real-world example (React/Vue/Svelte multi-framework org) Addresses feedback that web components should not be the primary pattern. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

mattpodwysocki · 2026-02-18T19:46:26Z

Updated: Restructured as Advanced Pattern (Option 1)

Based on docs team feedback, I've restructured the Web Components section to implement Option 1 - making it clear that framework-specific patterns are the primary approach, and Web Components are an advanced pattern for specific use cases.

Changes Made

1. Updated skill description

De-emphasized Web Components, focusing on framework-specific patterns
Changed from "frameworks and Web Components" to "React, Vue, Svelte, Angular"

2. Moved Web Components to new "Advanced Patterns" section

Positioned after all framework-specific patterns
No longer presented as equal alternative

3. Added prominent warning at section start

⚠️ Important: Web Components are an advanced pattern for specific use cases. If you're building a single-framework application (React-only, Vue-only, etc.), use the framework-specific patterns above instead.

4. Clearer "When to use" guidance

✅ Design systems & component libraries across frameworks
✅ Micro-frontends with multiple frameworks (React + Vue + Svelte)
✅ Multi-framework organizations
✅ Framework migration scenarios
❌ NOT for single-framework apps

5. Real-world example
"A company with React (main app), Vue (admin panel), and Svelte (marketing site) can build one <mapbox-map> component that works everywhere."

6. Condensed examples

Removed Shadow DOM pattern (too advanced)
Kept essential patterns only

Result

Web Components are now clearly positioned as an advanced pattern for:

Design systems
Multi-framework organizations
Micro-frontends

With clear guidance to use framework-specific patterns for typical single-framework applications.

The 'style' attribute conflicts with React's reserved 'style' prop for CSS. Changed to 'map-style' throughout Web Components examples: - Updated MapboxMap class to use getAttribute('map-style') - Updated MapboxMapReactive observedAttributes to ['center', 'zoom', 'map-style'] - Updated all usage examples (HTML, React, Vue, Svelte) - Updated attributeChangedCallback to handle 'map-style' case Addresses: #13 (comment) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

mattpodwysocki

Fixed! Changed all occurrences of style attribute to map-style to avoid conflict with React's reserved style prop.

Changes:

getAttribute('style') → getAttribute('map-style')
observedAttributes: ['center', 'zoom', 'style'] → ['center', 'zoom', 'map-style']
All usage examples updated (HTML, React, Vue, Svelte)
attributeChangedCallback updated to handle 'map-style' case

All examples now use:

<mapbox-map
  map-style="mapbox://styles/mapbox/standard"
  center="-122.4194,37.7749"
  zoom="12"
/>

This works safely in React and all other frameworks.

Previous warning was too strong and discouraged Web Components in general. Updated to clarify: - Web Components are great for vanilla JS apps (no added complexity) - Web Components are excellent for cross-framework scenarios - If using a framework, prefer framework-specific patterns FIRST (simpler) Key changes: - Removed "advanced pattern" and "add complexity" language - Added vanilla JavaScript as primary use case - Changed ❌ to 🔧 for framework guidance (less negative) - Added tip suggesting framework patterns first when applicable - Maintains clear guidance without discouraging Web Components generally Web Components don't add complexity to vanilla apps - they only add complexity if you're already using a framework and don't need cross- framework compatibility. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

mattpodwysocki · 2026-02-18T19:53:30Z

Updated: More Balanced Web Components Guidance

Revised the messaging to avoid discouraging Web Components in general. The previous warning was too strong.

Key Changes

Before:

⚠️ Web Components are an advanced pattern for specific use cases. Web Components add complexity...

After:

Web Components are a W3C standard for creating reusable custom elements that work in any framework or no framework at all.

New Guidance Structure

When to use Web Components:

✅ Vanilla JavaScript apps - No framework? Web Components are great (no added complexity)
✅ Design systems across frameworks
✅ Micro-frontends
✅ Multi-framework organizations

When to use framework-specific patterns instead:

🔧 Already using a framework (simpler, better integration)
🔧 Need framework features (hooks, composition API, etc.)
🔧 Team familiar with framework patterns

Added Tip:

💡 If you're using React, Vue, Svelte, or Angular, start with the framework-specific patterns above. Use Web Components when you need cross-framework compatibility or are building vanilla JavaScript apps.

Result

Doesn't discourage Web Components generally
Makes vanilla JS a primary use case
Clear: if using a framework, prefer framework patterns first
Web Components positioned as excellent choice for cross-framework needs

AndrewSepic

LGTM! Works as expected in the frameworks as tested. Thanks for the changes.

mattpodwysocki requested a review from a team as a code owner February 4, 2026 18:46

mattpodwysocki added 2 commits February 4, 2026 13:57

Add mapload and frontends to spell check dictionary

7e0664a

mattpodwysocki mentioned this pull request Feb 4, 2026

Add spell check entries for new skills #17

Merged

3 tasks

AndrewSepic reviewed Feb 18, 2026

View reviewed changes

mattpodwysocki and others added 3 commits February 18, 2026 14:45

Merge main into add-web-components-pattern

3594501

Fix formatting

6884c74

mattpodwysocki requested a review from a team as a code owner February 18, 2026 19:46

mattpodwysocki requested a review from AndrewSepic February 18, 2026 19:49

mattpodwysocki commented Feb 18, 2026

View reviewed changes

AndrewSepic approved these changes Feb 18, 2026

View reviewed changes

mattpodwysocki merged commit 0af0d0a into main Feb 18, 2026
1 check passed

mattpodwysocki deleted the add-web-components-pattern branch February 18, 2026 22:37

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add Web Components patterns to web integration skill#13

Add Web Components patterns to web integration skill#13
mattpodwysocki merged 8 commits intomainfrom
add-web-components-pattern

mattpodwysocki commented Feb 4, 2026

Uh oh!

AndrewSepic Feb 10, 2026 •

edited

Loading

Uh oh!

mattpodwysocki commented Feb 18, 2026

Uh oh!

mattpodwysocki left a comment

Uh oh!

mattpodwysocki commented Feb 18, 2026

Uh oh!

AndrewSepic left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

mattpodwysocki commented Feb 4, 2026

Summary

What's Added

Patterns Covered

Basic Web Component

Usage Across Frameworks

Advanced Patterns

Benefits

When to Use

When to Use Framework Components Instead

Testing

Uh oh!

AndrewSepic Feb 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mattpodwysocki commented Feb 18, 2026

Updated: Restructured as Advanced Pattern (Option 1)

Changes Made

Result

Uh oh!

mattpodwysocki left a comment

Choose a reason for hiding this comment

Uh oh!

mattpodwysocki commented Feb 18, 2026

Updated: More Balanced Web Components Guidance

Key Changes

New Guidance Structure

Result

Uh oh!

AndrewSepic left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

AndrewSepic Feb 10, 2026 •

edited

Loading